QuickTime 3 Reference

| Previous | Chapter Contents | Chapter Top | Next |

NewMovieFromUserProc

The NewMovieFromUserProc function creates a movie from data that you provide. Your application defines a function that delivers the movie data to the Movie Toolbox. The toolbox calls your function, specifying the amount of data required and the location for the data.

pascal OSErr NewMovieFromUserProc (Movie *m, short flags, Boolean *dataRefWasChanged,
                     GetMovieUPP getProc, void *refCon, Handle defaultDataRef,
                     OSType dataRefType);


m

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil .

newMovieFlags

Controls the operation of the NewMovieFromUserProc function. The following flags are valid (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function.

newMovieDontResolveDataRefs

Controls how completely the toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on remote volumes. If you set this flag to 1, the toolbox only looks in the specified data reference.

If the toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the toolbox also sets the current error value to couldNotResolveDataRef .

newMovieDontAskUnresolvedDataRefs

Controls whether the toolbox asks the user to locate files. If you set this flag to 0, the toolbox asks the user to locate files that it cannot find on available volumes. If the toolbox cannot locate a file even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef .

newMovieDontAutoAlternate

Controls whether the toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the toolbox does not automatically select tracks for the movie--you must enable and disable tracks yourself.

dataRefWasChanged

Contains a pointer to a Boolean value. The toolbox sets the Boolean to indicate whether it had to change any data references while resolving them. The Toolbox sets the Boolean value to true if any references were changed. Use the UpdateMovieResource function to preserve these changes.

Set the dataRefWasChanged parameter to nil if you do not want to receive this information.

getProc

Contains a pointer to a function in your application. This function is responsible for providing the movie data to the toolbox.

refCon

Contains a reference constant (defined as a void pointer). The toolbox provides this value to the function identified by the getProc parameter.

defaultDataRef

Specifies the default data reference. This parameter contains a handle to the information that identifies the file to be used to resolve any data references and as a starting point for any Alias Manager searches.

The type of information stored in the handle depends upon the value of the dataRefType parameter. For example, if your application is loading the movie from a file, you would refer to the file's alias in the defaultDataRef parameter, and set the dataRefType parameter to rAliasType .

If you do not want to identify a default data reference, set the parameter to nil .

dataRefType

Specifies the type of data reference. If the data reference is an alias, you must set the parameter to rAliasType , indicating that the reference is an alias.

NewMovieFromFile

The NewMovieFromFile function (QuickTime 2.0 or later) works with some files that do not contain movie resources. In some cases, the data in a file is already sufficiently well formatted for QuickTime or its components to understand. For example, the AIFF movie data import component can understand AIFF sound files and import the sound data into a QuickTime movie.

When the NewMovieFromFile function encounters a file that does not contain a movie resource, the function tries to find a movie import component that can understand the data and create a movie. For more information about new capabilities of movie data import components, see " Movie Data Exchange Components." This also works for MPEG, uLaw ( .AU ), and Wave ( .WAV ) file types.

NewMovieFromDataRef

Use the new NewMovieFromDataRef function to create a movie from any device with a corresponding data handler. You are no longer restricted to instantiating a movie from a file stored on an HFS volume. With this new function, you can now instantiate a movie from any device.

pascal OSErr NewMovieFromDataRef (
                     Movie *m,
                     short flags,
                     short *id,
                     Handle dataRef,
                     OSType dataRefType);


m

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil .

flags

Controls the operation of the NewMovieFromDataRef function. The following flags are valid (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function.

newMovieDontResolveDataRefs

Controls how completely the toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on remote volumes. If you set this flag to 1, the toolbox only looks in the specified data reference.

If the toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the toolbox also sets the current error value to couldNotResolveDataRef .

newMovieDontAskUnresolvedDataRefs

Controls whether the toolbox asks the user to locate files. If you set this flag to 0, the toolbox asks the user to locate files that it cannot find on available volumes. If the toolbox cannot locate a file, even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef .

newMovieDontAutoAlternate

Controls whether the toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the toolbox does not automatically select tracks for the movie--you must enable and disable tracks yourself.

id

Contains a pointer to the field that specifies the resource containing the movie data that is to be loaded. If the field referred to by the id parameter is set to 0, the toolbox loads the first movie resource it finds in the specified file. The toolbox then returns the movie's resource ID number in the field referred to by the id parameter. The following enumerated constant is available:

movieInDataForkResID

Indicates the movie was loaded from the data fork. If the resource was stored in the file's data fork, the toolbox sets the returned value to movieInDataForkResID(-1) . In this case, you cannot add a movie resource to the file unless you create a resource fork in the movie file.

If the id parameter is set to nil , the toolbox loads the first movie resource it finds in the specified file and does not return that resource's ID number.

dataRef

Specifies the default data reference. This parameter contains a handle to the information that identifies the file to be used to resolve any data references and as a starting point for any Alias Manager searches.

The type of information stored in the handle depends upon the value of the dataRefType parameter. For example, if your application is loading the movie from a file, you would refer to the file's alias in the DataRef parameter and set the dataRefType parameter to rAliasType .

If you do not want to identify a default data reference, set the parameter to nil .

dataRefType

Specifies the type of data reference. If the data reference is an alias, you must set the parameter to rAliasType , indicating that the reference is an alias.

ConvertFileToMovieFile

As of QuickTime 1.6.1, the ConvertFileToMovieFile function supports a user settings dialog box for import operations. Your application controls whether this dialog box appears by setting the value of the flags parameter in the ConvertFileToMovieFile function. This function supports the following new flag:

showUserSettingsDialog

Controls whether the user settings dialog box for the specified import operation can appear. Set this flag to 1 to display the user settings dialog box.

ConvertMovieToFile

The ConvertMovieToFile function now supports a "Save As..." dialog box. The dialog box allows the user to specify the file name and type. Supported types include standard QuickTime movies, flattened movies, single-fork flattened movies, and any format that is supported by a movie data export component. Figure 1-10 shows a sample "Save As..." dialog box.

Figure 10 Sample "Save As..." dialog box

Your application controls whether this dialog box appears by setting the value of the flags parameter for the ConvertMovieToFile function. The function supports the following flags:

showUserSettingsDialog

If this bit is set, the Save As dialog box will be displayed to allow the user to choose the type of file to export to, as well as the file name to export to.

movieToFileOnlyExport

If this bit is set and the showUserSettingsDialog bit is set, the Save As dialog box restricts the user to those file formats that are supported by movie data export components.

movieFileSpecValid

If this bit is set and the showUserSettingsDialog bit is set, the name field of the outputFile parameter is used as the default name of the exported file in the Save As dialog box.

The following code shows how to call this function to provide a simple export capability.

err = ConvertMovieToFile (theMovie,     /* identifies movie */
                    nil,                /* all tracks */
                    nil,                /* no output file */
                    0,                  /* no file type */
                    0,                  /* no creator */
                    -1,                 /* script */
                    nil,                /* no resource ID */
                    createMovieFileDeleteCurFile |
                        showUserSettingsDialog |
                        movieToFileOnlyExport,
                    0);                 /* no specific component */


FlattenMovie and FlattenMovieData

Through the new SetTrackLoadSettings function, the Movie Toolbox, now allows you to set a movie's preloading guidelines when you create the movie. The preload information is preserved when you save or flatten the movie (using either the FlattenMovie or FlattenMovieData functions). In flattened movies, the tracks that are to be preloaded are stored at the start of the movie, rather than being interleaved with the rest of the movie data. This greatly improves preload performance because it is not necessary for the device storing the movie data to seek during retrieval of the data to be preloaded.

For more information about preloading, see the discussion of the SetTrackLoadSettings function in "Enhancing Movie Playback Performance" .

Instead of flattening to a file, you can now also specify a data reference to flatten a movie to. The FSSpec parameter for the FlattenMovieData function usually contains a pointer to the file system specification for the movie file to be created. In place of the FSSpec parameter, QuickTime lets you pass a pointer to a data reference structure. The data reference structure defines the data reference to flatten the movie data to. For more information about this structure, see "Data Types" .